<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "DTD/xhtml1-strict.dtd">
<html>
  <head>
    <title>API docs for &ldquo;pymine.miner.MineAPI&rdquo;</title>
    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" />
    <link href="apidocs.css" type="text/css" rel="stylesheet" />
    
    
  </head>
  <body>
    <h1 class="class">Class p.m.MineAPI:</h1>
    <p>
      <span id="part">Part of <a href="pymine.html">pymine</a>.<a href="pymine.miner.html">miner</a></span>
      
      <a href="classIndex.html#pymine.miner.MineAPI">View In Hierarchy</a>
    </p>
    <div>
      
    </div>
    <div>There are essentially two ways to use Miner; first you instantiate 
it:</p>
<p>m = MineAPI(**apiopts)</p>
<p>...and then either you treat it like a client library:</p>
<p>foo = m.create_item(name=&quot;Something&quot;) print foo tags = 
m.list_tags()</p>
<p>...or you treat it like the command_line interface:</p>
<p>foo = m.command_line(&quot;create-item&quot;, 
&quot;name=Something&quot;) print foo tags = 
m.command_line(&quot;list-tags&quot;)</p>
<p>If going down the latter route, don't mess around with the XML-output 
options otherwise nothing good will come of it.</p>
<p>If going down the command_line route, the &quot;delete-*&quot; methods 
implement a &quot;__FAKE_ITERATION_KLUDGE__&quot; - in other words you can 
pass multiple thing IDs into the command_line and they will be serially 
deleted, even though the underlying library calls do not take multiple 
arguments.  This exists only for the beenfit of actual commandline (shell) 
users, and shouldn't be used programmatically since it makes a nonsense of 
exception handling.<table class="fieldTable"></table></div>
    
    
    <div id="splitTables">
      <table class="children sortable" id="id139">
  
  
  
  
  <tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#__init__">__init__</a></td>
    <td><span>Initialise a MineAPI object; Recognised kwargs include:</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#set_url_prefix">set_url_prefix</a></td>
    <td><span>Define the 'http://site.domain:port' to access your mine, if</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#login">login</a></td>
    <td><span>Establish session cookies.  Accepts 'username' and 'password'</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#logout">logout</a></td>
    <td><span>Call the mine to destroy any session cookies</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#url_call">url_call</a></td>
    <td><span>talks to the mine via the API, returns a response object from 
urllib2</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#apply">apply</a></td>
    <td><span>Invokes url with method using kwargs as POST data if</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#apply_sub1">apply_sub1</a></td>
    <td><span>Replaces '{1}' in url_template with arg[0]; invokes resulting</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#apply_sub1_regkey">apply_sub1_regkey</a></td>
    <td><span>Replaces '{1}' in url_template with arg[0]; invokes resulting</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#apply_sub2">apply_sub2</a></td>
    <td><span>Replaces '{1}' in url_template with arg[0]; replaces '{2}' in</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#call">call</a></td>
    <td><span>invokes the apply() function and parameters associated with</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#call_py">call_py</a></td>
    <td><span>Exactly as-per call() but the result is decoded into a</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#__getattr__">__getattr__</a></td>
    <td><span>this getattr overrides the default and via a clever and</span></td>
  </tr><tr class="method">
    
    
    <td>Method</td>
    <td><a href="pymine.miner.MineAPI.html#command_line">command_line</a></td>
    <td><span>Takes an argument list, and executes it</span></td>
  </tr>
  
</table>
      
      
    </div>
    
    
    
    <div class="function">
        <a name="pymine.miner.MineAPI.__init__"></a>
        <a name="__init__"></a>
        <div class="functionHeader">
        
        def __init__(self, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Initialise a MineAPI object; Recognised kwargs include:</p>
<p>output_format url_prefix username password</p>
<p>Automatically calls login() if both username and password are given.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.set_url_prefix"></a>
        <a name="set_url_prefix"></a>
        <div class="functionHeader">
        
        def set_url_prefix(self, url_prefix):
        
      </div>
        <div class="functionBody">
          
          <div>Define the 'http://site.domain:port' to access your mine, if not already
provided to __init__()<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.login"></a>
        <a name="login"></a>
        <div class="functionHeader">
        
        def login(self, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Establish session cookies.  Accepts 'username' and 'password' kwargs, 
overriding any provided in __init__()<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.logout"></a>
        <a name="logout"></a>
        <div class="functionHeader">
        
        def logout(self, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Call the mine to destroy any session cookies<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.url_call"></a>
        <a name="url_call"></a>
        <div class="functionHeader">
        
        def url_call(self, method, url_suffix, form_data):
        
      </div>
        <div class="functionBody">
          
          <div>talks to the mine via the API, returns a response object from 
urllib2<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.apply"></a>
        <a name="apply"></a>
        <div class="functionHeader">
        
        def apply(self, method, url_template, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Invokes url with method using kwargs as POST data if appropriate.  
Completely ignores args.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.apply_sub1"></a>
        <a name="apply_sub1"></a>
        <div class="functionHeader">
        
        def apply_sub1(self, method, url_template, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Replaces '{1}' in url_template with arg[0]; invokes resulting url with 
method using kwargs as POST data if appropriate.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.apply_sub1_regkey"></a>
        <a name="apply_sub1_regkey"></a>
        <div class="functionHeader">
        
        def apply_sub1_regkey(self, method, url_template, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Replaces '{1}' in url_template with arg[0]; invokes resulting url with 
method using faked-up kwargs:</p>
<p>{ arg[0] : arg[1] } # eg: { 'foo': 42 }</p>
<p>...because this syntax is used to populate individual keys in the 
registry (applying { 'foo':42 } to /api/registry/foo.json)<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.apply_sub2"></a>
        <a name="apply_sub2"></a>
        <div class="functionHeader">
        
        def apply_sub2(self, method, url_template, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Replaces '{1}' in url_template with arg[0]; replaces '{2}' in 
url_template with arg[1]; invokes resulting url with method using kwargs as
POST data if appropriate.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.call"></a>
        <a name="call"></a>
        <div class="functionHeader">
        
        def call(self, command, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>invokes the apply() function and parameters associated with the command,
and returns the (presumably) JSON string that results.</p>
<p>'args' are interpolated into the template (if applicable)</p>
<p>'kwargs' become POST data (if applicable and not overridden)<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.call_py"></a>
        <a name="call_py"></a>
        <div class="functionHeader">
        
        def call_py(self, command, *args, **kwargs):
        
      </div>
        <div class="functionBody">
          
          <div>Exactly as-per call() but the result is decoded into a python data 
structure and is returned.</p>
<p>Do NOT set the format to anything other than default(None - implying 
json) if you are using this or any of the virtual methods that are provided
by __getattr__()<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.__getattr__"></a>
        <a name="__getattr__"></a>
        <div class="functionHeader">
        
        def __getattr__(self, attr):
        
      </div>
        <div class="functionBody">
          
          <div>this getattr overrides the default and via a clever and slightly evil 
kludge implements the following virtual methods:</p>
<p>create_comment() create_feed() create_item() create_tag() create_vurl() 
delete_comment() delete_comment_key() delete_feed() delete_feed_key() 
delete_item() delete_item_key() delete_registry_key() delete_tag() 
delete_tag_key() delete_vurl() delete_vurl_key() list_comments() 
list_feeds() list_items() list_registry() list_tags() list_vurls() 
read_comment() read_comment_key() read_data() read_feed() read_feed_key() 
read_icon() read_item() read_item_key() read_registry_key() read_tag() 
read_tag_key() read_vurl() read_vurl_key() update_comment() update_feed() 
update_item() update_registry_key() update_tag() update_vurl() 
version()</p>
<p>so you can do stuff like:</p>
<p>m = MineAPI(username='fred, ...') tags = m.list_tags()</p>
<p>...even though no list_tags() method is defined; this works because 
__getattr__() traps the attempt to access the nonexistent list_tags method,
converts underscores to hyphens and then returns a lambda that frontends 
call_py() with the properly 'command' inserted.</p>
<p>The net result is: any 'foo-bar' API call is also available as 
api.foo_bar() yielding python structures.<table class="fieldTable"></table></div>
        </div>
      </div><div class="function">
        <a name="pymine.miner.MineAPI.command_line"></a>
        <a name="command_line"></a>
        <div class="functionHeader">
        
        def command_line(self, cmdargs):
        
      </div>
        <div class="functionBody">
          
          <div>Takes an argument list, and executes it</p>
<p>Any arguments not containing the '=' character go into a dictionary of 
kwargs that are passed into the followup methods, and eventually into POST 
data</p>
<p>Example: create-tag tagName=&quot;foo&quot; tagDescription=&quot;example
tag&quot;</p>
<p>Any arguments not containing the '=' character are appended to a plain 
list that is supplied to the wrapper around the REST API invocation, which 
may (if you are doing it right) iterate over those arguments and do 
something useful.</p>
<p>Example: delete-tag 1 2 5 7 9 ...</p>
<p>These concepts probably can mix-and-match, but it'd be deeply advanced 
for anyone to try doing so at the moment.</p>
<p>This routine also kludges a loop construct atop the api calls for 
most/all of the deletion routines, for the benefit of command_line users 
ONLY; programmers talking to the API are expected to use iteration.<table class="fieldTable"></table></div>
        </div>
      </div>
    
    <address>
      <a href="index.html">API Documentation</a> for pymine, generated by <a href="http://codespeak.net/~mwh/pydoctor/">pydoctor</a> at 2010-04-07 23:15:24.
    </address>
  </body>
</html>